home *** CD-ROM | disk | FTP | other *** search
/ System Booster / System Booster.iso / Commodities / Nag 1.14 / Nag.doc < prev    next >
Text File  |  1996-09-26  |  11KB  |  312 lines
  1. ----------------------------------------------------------------------------
  2.  
  3.                                   Nag 1.14
  4.  
  5. ----------------------------------------------------------------------------
  6.  
  7.  
  8. The files in this archive were written by David Walthour and are freely
  9. distributable as long as the archive remains intact, and only a nominal fee
  10. is charged for its distribution.
  11.  
  12. This software is provided "AS IS" without warranty of any kind, either
  13. expressed or implied. By using it, you agree to accept the entire risk as to
  14. the quality and performance of the program.
  15.  
  16. Comments, suggestions and bug reports are welcome.
  17.  
  18.    David Walthour
  19.    55 Sachem Village
  20.    W Lebanon, NH  03784 USA
  21.  
  22.    walthour@dartmouth.edu
  23.  
  24.  
  25.  
  26. Intro
  27. -----
  28.  
  29. Nag is a scheduler/reminder commodity written for OS 2.04.  It is designed
  30. keep track of an unlimited number of events and, at the time of the event,
  31. flash the screen and display a requester to remind you of it.  It can be
  32. configured to display a reminder for an event occuring only once or for 
  33. events that occur on a weekly basis.  Currently Nag cannot handle semi-
  34. weekly, monthly, or yearly events.
  35.  
  36.  
  37. New features for v1.14
  38. ----------------------
  39.  
  40. Nag v1.13 now can handle pattern matching in the date format of the event entry.
  41. This allows the definition of events which will happen on a monthly or yearly
  42. basis as well as on more complicated schedules.  The wildcard character is
  43. '?' and can be used in place of the year, month, or day field or any
  44. combination of those fields.  For example, these are now valid entries:
  45.  
  46. 8:00am 4/1/? April Fools Day!
  47.  
  48. 12:00am 1/1/? Happy New Years!
  49.  
  50. 9:30pm ?/31/? This is the 31st of the month
  51.  
  52.   [Note: the above will only occur on months with 31 days in them]
  53.  
  54. 1:30pm 6/?/? Its a beautiful afternoon in June!
  55.  
  56. 1:30pm 6/?/93 Its a beautiful afternoon in June of 1993!
  57.  
  58. 5:00pm ?/?/? Its five o'clock
  59.  
  60.  
  61. Installation
  62. ------------
  63.  
  64. Two versions of Nag are included in this archive: the regular version (Nag)
  65. and a version compiled for the 68030 processor (Nag.030).
  66.  
  67. Nag can be executed from the cli or from the Workbench and accepts the 
  68. three standard commodity tool types:
  69.  
  70. CX_PRIORITY      (Default = 0)
  71. CX_POPUP         (Default = YES)
  72. CX_POPKEY        (Default = CTRL ALT N)
  73.  
  74.  
  75. Nag also has three tool types to control its date format and "nag later"
  76. delay:
  77.  
  78. DATE_FORMAT      This can be set to either DAY_FIRST or MONTH_FIRST
  79.                  depending on your preference.  It defaults to 
  80.                  MONTH_FIRST
  81.  
  82. DATE_DIVIDER     This can be set to:
  83.                    SLASH for the date divider to be '/' (i.e., 3/25/93)
  84.                    DASH  for the date divider to be '-' (i.e., 3-25-93)
  85.                    DOT   for the date divider to be '.' (i.e., 3.25.93)
  86.                  It defaults to SLASH
  87.  
  88. NAG_LATER_DELAY  This is set to the number of minutes that Nag should delay
  89.                  before redisplaying the message when the "Nag in X min" 
  90.                  button is chosen from the event requester.  It defaults
  91.                  to 5 minutes.
  92.                  
  93.  
  94. The best place to install Nag is in your WBStartup drawer with the tool
  95. type DONOTWAIT.  It can also be placed in your user-startup script.
  96.  
  97.  
  98. Using Nag
  99. ---------
  100.  
  101. When Nag's user interface is displayed, the window will contain a list of
  102. all events that Nag is currently remembering along with four other buttons:
  103. New, Del, Hide, and Quit.  Clicking on an event in the listview
  104. gadget (the list) will move this event into the string gadget (which is
  105. below the list) and will allow this event to be edited.  This will also 
  106. enable the Del button.  When you are done editing an event, pressing return
  107. will reenter the event into the list.  
  108.  
  109. The functions of the buttons are as follows:
  110.  
  111. New:  This button turns on and clears the string gadget at the bottom of 
  112.       the listview gadget and allows the user to enter a new event to 
  113.       remember.  Pressing return causes the event to entered into the
  114.       list.
  115.  
  116. Del:  This button will delete the event currently being edited in from the
  117.       list of remembered events.
  118.       
  119. Hide: This button will cause the user interface window to dissappear.  It 
  120.       can be made to reappear by either pressing Nag's hotkey combination
  121.       or by using C='s commodities exchange program.
  122.       
  123. Quit: This button quits Nag and removes it from the OS commodities list.
  124.  
  125.  
  126. The Hide and Quit functions can also be accessed from the pull-down
  127. menus.
  128.  
  129.  
  130. Entering an Event
  131. -----------------
  132. The syntax for an event takes one of two forms:
  133.  
  134. <hh:mm>[AM|PM] <mm/dd/yy> <message>
  135.  
  136. or
  137.  
  138. <hh:mm>[AM|PM] <day of week> <message>
  139.  
  140.  
  141. where:
  142.  
  143. <hh:mm>[AM|PM] is the time at which the event takes place in hours and
  144.                minutes.  The AM or PM is optional.  If they are not
  145.                included, the time is assumed to be in 24-hour format.
  146.                  hh = the hour of the event (either 0-23 or 1-12 depending
  147.                       if the AM|PM is present)
  148.                  mm = the minute of the event (0-59)
  149.  
  150. <mm/dd/yy>     is the date of the event.  Note that by using the tool types
  151.                described above, this format can be changed in a number of
  152.                ways.  All possible formats are: <mm/dd/yy>, <dd/mm/yy>,
  153.                <mm-dd-yy>, <dd-mm-yy>, <mm.dd.yy>, and <dd.mm.yy> 
  154.                where: 
  155.                   mm = the number of the month (1-12)
  156.                   dd = the day of the month
  157.                   yy = the last two digits of the year
  158.                Any of these three fields can be replaced by the wildcard
  159.                symbol '?'.  The next date which matches the specified 
  160.                pattern will be the date of the event.
  161.  
  162. <day of week>  is the day(s) of the week that the event takes place on.  
  163.                Each day is given a one character abbreviation as follows:
  164.                    M = Monday
  165.                    T = Tuesday
  166.                    W = Wednesday
  167.                    H = Thursday
  168.                    F = Friday
  169.                    S = Saturday
  170.                    U = Sunday
  171.                
  172.                More than one day can be entered for an event, e.g., MWF
  173.                would indicate that this event takes place on Mondays
  174.                Wednesdays and Fridays, SU would indicate that this event
  175.                occurs on the weekends, etc.
  176.                
  177. <message>      is the text that will be displayed in the requester when 
  178.                the event occurs.
  179.                
  180. Spaces are ignored and the abbreviations are not case sensitive.
  181.  
  182. As the events are entered they will be sorted into order of occurance with
  183. the events that will occur first at the top of the list.  If an event has
  184. already passed and will not be occuring again, it appears at the bottom
  185. of the list with an asterisk (*) preceding it.  If Nag was unable to 
  186. understand the event you have typed, it appears at the bottom of the list 
  187. with a number sign (#) preceding it.
  188.  
  189.  
  190. Examples
  191. --------
  192.  
  193. For instance, if you have a class on Tuesdays and Thursdays at 2:00 and you
  194. would like to be notified 10 minutes prior to this, you would enter:
  195.  
  196. 1:50pm TH Time to go to class
  197.  
  198. or
  199.  
  200. 13:50 TH Time to go to class
  201.  
  202.  
  203. Other examples might be:
  204.  
  205. 7:00pm 4/28/93 Call Mom for her Birthday!
  206.  
  207. 12:00PM MtWHf Lunchtime
  208.  
  209. 0:30 MTWHFSU Its 30 minutes past midnight
  210.  
  211. 8:00am 4/1/? April Fools Day!
  212.  
  213. 12:00am 1/1/? Happy New Years!
  214.  
  215. 9:30pm ?/31/? This is the 31st of the month
  216.  
  217.   [Note: the above will only occur on months with 31 days in them]
  218.  
  219. 1:30pm 6/?/? Its a beautiful afternoon in June!
  220.  
  221. 1:30pm 6/?/93 Its a beautiful afternoon in June of 1993!
  222.  
  223. 5:00pm ?/?/? Its five o'clock
  224.  
  225.  
  226. Planned Improvements
  227. --------------------
  228.  
  229. - GUI for entering the date and time of an event
  230.  
  231. - Ability to post an advance notice requester for an event.
  232.  
  233. - capability to handle events which are semi-weekly, etc.
  234.  
  235.  
  236. Known Bugs
  237. ----------
  238.  
  239. Occasionally my system has crashed when I quit from Nag with a "Memory List
  240. Corrupt" error.  This has happened VERY infrequently and with such
  241. randomness that I can't yet locate the error and am not even sure that it is
  242. a problem with Nag.  The program IS ENTIRELY STABLE when running and since
  243. it is designed such that it SHOULD always be running, this shouldn't be a 
  244. problem.  However, if you do come across this bug, I would appreciate
  245. any info you can give me about the occurance (programs that were also
  246. installed when Nag was running, etc.)
  247.  
  248.  
  249. History
  250. -------
  251.  
  252. v1.00  3/10/93, 16268 bytes
  253.    o First release including source code.
  254.    
  255. v1.01  3/11/93  16264 bytes
  256.    o Fixed an enforcer hit that got by me.
  257.  
  258. v1.1   3/25/93  18428 bytes
  259.    o Many bugs fixed and new features added:
  260.    
  261.      - The gui is now font sensitive based on the system default font
  262.      
  263.      - Nag keeps track of events that have passed since it was last active and
  264.        reports these upon startup.  A consequence of this is that Nag 
  265.        automatically saves the events and the 'Save' button and menu option 
  266.        have been removed
  267.      
  268.      - Nag is now more compliant with the C= style guide
  269.      
  270.      - Nag has new tool types DATE_FORMAT and DATE_DIVIDER to set the format for
  271.        the date input
  272.        
  273.      - Nag has a "nag later" option when the event requester appears so that you
  274.        can have it nag you again in a number of minutes specified by the 
  275.        NAG_LATER_DELAY tool type
  276.      
  277.      - The string gadget no longer loses its contents when an event occurs
  278.      
  279.      - The leading '#' or '*' is deleted before editing any events which have
  280.        these symbols as their first characters
  281.      
  282.      - Lots of other bugs fixed
  283.  
  284.  
  285. v1.11a  3/26/93  18564 bytes
  286.    o Fixed a few enforcer hits that I missed
  287.    o Changed the gui so that it uses the screen font rather than the system 
  288.      default font
  289.  
  290. v1.12a 3/28/93  19176 bytes
  291.    o Fixed problem which caused Arq v1.78 to crash when used with Nag v1.11.
  292.      It seems that Arq can't be called from a task, it must be called from a
  293.      process.  Thanks to John Palfrey for pointing this out!
  294.    o Added requesters to display any internal errors which cause the program
  295.      to fail.  Thanks to Martin Ozolins for this suggestion.
  296.  
  297. v1.13  3/31/93  19968 bytes
  298.    o Fixed bug in month rollover for events specified by day.
  299.    o Fixed code so that if events which occur while a requester is up, they 
  300.      will be displayed after responding to the requester.
  301.    o Nag now handles dates past 1999 correctly
  302.    o Fixed other small bugs.
  303.    o Added date wildcard feature so that events can be set to occur monthly or
  304.      yearly (as well as in other combinations).
  305.  
  306. v1.14  4/1/93   19988 bytes
  307.    o Fixed mistake which caused the reporting of messages at startup to 
  308.      disappear.
  309.    o Fixed bug which caused trouble in listview gadget for OS 3.0
  310.    o Fixed small bug with tool types which caused problems with OS 2.04
  311.      (2.04 doesn't allow 'ctrl' as an abbreviation for 'control')
  312.